Programmers Quick Guide to MCs Menu Maker v0.8 ---------------------------------------------- Ok,so its not that quick a guide!,but there should be enough information here to allow use of the menus/windows without any further documentation. A list of all the functions that are necessary in order to create and maintain a menu and/or window structure are listed below.Example code to illustrate each call is also included,with a full working skeleton at the end of this documentation.Note:If a window is linked to a menu then on being displayed it will use its defaults however,if the window is displayed using window_show the gadget values are taken from the windows work area and therefore must be set first with win_set_item.Bascially if you *always* require the default values to be used then link the window to a menu otherwise you have to manage the window work area yourself (a demonstration of this in included at the end). Cursor keys allow up/down movement on the menus while tab allows input to circle around all a windows options. void menu_clear(int 1) ---------------------- Parameter 1 is a number representing the main background screen colour to be used.This function must be called first before any others as it contains code to initialize the menu/window system. Example: -------- menu_clear(1); Menu/window system will be initialized and main background colour will be 1, standard EGA/VGA 16 colour scheme is used (see documentation for list). void menu_declare(char *1) -------------------------- This call allows each possible selection on a menu to be declared.To link a particular option to a window the window number is contained in curly brackets before the option.Window and menu numbers are assigned depending on the order of declaration e.g. the first defined menu is menu 0 the second menu 1 etc, the same applies to windows. Example: -------- menu_declare("A menu,{3}This option opens a window"); A menu will be defined,its number is dependant on if any other menus were created before it (as the above is an example of the first menu declaration its number will be 0).The first option in the menu will be the text "A menu" it has no direct link to a window,on selection it will set the global variables menu_option and menu_number,in this example both would equal 0 - for menu 0, option 0 selected.The second option would insert the text "This option opens a window",on selection window 3 would be openned and input would now be into this window.Note,no menus are actually displayed until a menu_display is issued. void window_declare(char *1,int 2,int 3,int 4,int 5,char *6) ------------------------------------------------------------ Allows a window to be defined.The order of declaration will define the window number.All window declarations must end in a curly bracketed 0.Parameter 1 allows for an automatically centered window title to be displayed,if this is left as a null ("") then no title will be displayed.Parameters 2 and 3 are the windows size in characters (x,y).Parameters 4 and 5 determine the x,y coordinate to place the window at,if both are 0 then the window is placed below and slightly to the right (where ever possible) of the menu option that selected it. If either value is not 0 then the window is placed directly at these coordinates (origin top left 0,0).The final parameter 6 contains the window gadget types required,currently supported types are listed below.Note all x,y coordinates are relative to the windows origin. type 1 text (x,y,col,string) Parameters x,y are the coordinates to place the text at.Col is the colour to use to display text and finally string is the actual text itself. Example: -------- "{1}{10}{9}{15}Some text" The text "Some text" will be displayed at coordinates 10,9 in colour 15. type 2 switcher (x,y,num,def) Parameters x,y are the coordinates to place the first switch at.Num is the total number of switches displayed.Finally def is the number of the default switch to be highlighted. Example: -------- "{2}{3}{4}{4}{2}" 4 switches will be displayed starting at coordinates 3,4,switch 2 is the default hence highlighted one. type 3 number (x,y,min,max,def) Parameters x,y are the coordinates to place the input box.Min and Max define the minimum and maximum value to accept.Def is the default value. Example: -------- "{3}{10}{11}{5}{10}{6}" An input box will displayed at coordinates 10,11,it will accept only values between 5 and 10 inclusive.The default value is 6. type 4 boolean (x,y,def) Parameters x,y are the coordinates to place the alternator at.Def is the default selection (1=Yes,0=No). Example: -------- "{4}{7}{4}{1}" A boolean alternator will be displayed at coordinates 7,4.Its default will be YES. type 5 file (x,y,height,type) Parameters x,y are the coordinates to place the start of the file box at.Height is the height of the box in characters.Type defines what action to take on a selection,(0=exit on selection of file to calling program,1=don't,this allows for just directory selection).The current directory will be used. Example: -------- "{5}{6}{7}{10}{0}" A file selection box will be displayed at coordinates 6,7.Its height will be 10 characters.On a file selection control will return to the calling enviroment. type 6 char (x,y,len,type,def) Parameters x,y are the coordinates to place the start of the input box at.Len is the maximum length of input string to accept.Type defines what action to take on being pressed,(0=normal, string is stored but no action taken,1=exit on entry to calling program).Def is the default string to be displayed. Example: -------- "{6}{17}{8}{10}{0}" An input box will be displayed at coordinates 17,8.Maximum input length of string will be 10 characters.On no action will result,apart from storage of the string. type 7 accept (x,y,text) Parameters x,y are the coordinates to place the icon at.Text is the actual icon text to display. Example: -------- "{7}{6}{22}OK" An icon will be displayed at coordinates 6,22.Its text will be "OK". Full Example: ------------- window_declare("A window",50,20,0,0,"{1}{2}{2}{9}Hi,{3}{2}{5}{2}{10}{5},{0}"); A window with title "A window" of size 50,20 will be declared.When displayed it will appear one character down and one character to the right of the menu option that selected it if possible.The text string "Hi" will be displayed in colour 9 at coordinates 2,2.A number input box will be displayed at coordinates 2,5 it will accept a value between 2 and 10 inclusive,with the default displayed value being 5.Note the {0} terminator. int window_show(int 1,int 2,int 3) ---------------------------------- Window with the number parameter 1 will be displayed at coordinates parameter 2,parameter 3.This allows windows to be used without a menu selection being made or without any menus at all.The returned value is either the ASCII code of a 'non-window' key or a status value (see documentation).Note:default gadget values are overwrote as any values are read from the gadgets work space. Example: -------- key=window_show(5,10,10); Display window 5 at coordinates 10,10. void window_help_declare(int 1,int 2,char *3) --------------------------------------------- A window option must have a help string attached to it (null for none). Parameter 1 defines which window the help is attached to.Parameter 2 defines which gadget within that window the help is attached to.Parameter 3 is the help string to be displayed.Note a text gadget has no help string. Example: -------- window_declare("",10,10,0,0,"{2}{1}{1}{2}{1},{5}{2}{4}{4}{1},{0}"); window_help_declare(0,1,"Please select a file to load"); The window declaration defines a window with no title of size 10,10 and displayed slightly offset from its menu selection.A switcher is displayed at coordinates 1,1 with 2 switches and switch 1 the default.A file selector is also displayed at coordinates 2,4,its height is 4 characters.On any file selection no action is taken.The window_help_declare defines a help string for window 0 (assuming the window defined above was the first),item 1 (the file selector) and finally the actual help text to appear. void menu_help_declare(int 1,int 2,char *3) ------------------------------------------- A menu option must have help text attached to it ("" for none).Parameter 1 defines which menu will have the help.Parameter 2 defines which option within the menu will recieve the help.Parameter 3 is the actual help text. Example: -------- menu_declare("{0}About,How to register"); menu_help_declare(0,0,"All about this program"); menu_help_declare(0,1,""); The menu declaration defines a menu with two options,"About" links to window 0 on selection and "How to register" has no link or help.The menu_help_declare defines a help string for menu 0 (assuming the menu defined above was the first),item 0 (the "About" string) and finally the help text for that option. void win_set_item(int 1,int 2,long int 3) ----------------------------------------- This allows a window gadgets value to be set.Parameter 1 specifies the window number.Parameter 2 specifies which item within that window.Parameter 3 is the value to set it to,int long is used so that the setting of addresses can be allowed.Settings would be thus: type 1 text No setable parameters. type 2 switcher A value indicating which switch is active. type 3 number A value indicating the value to be displayed. type 4 boolean A value indicating whether the setting is YES(1) or NO(0). type 5 file The value here is an address to where the file selected is stored (accessed with win_get_item),therefore this value should not be altered. But the contents of its address will be the first character of the file selected (0 terminated). type 6 char The value here is an address to where the string is stored (accessed with win_get_item),therefore this value should not be altered.But the contents of its address will be the first character of the entered string (0 terminated). type 7 accept The value here is either a 1(icon selected) or a 0(not selected).Its the user programs resposibility to reset an icon once its selection has been dealt with.This is not necessary with only one icon in a window,but with more all must be reset after a selection otherwise next time the window is openned it will not be possible to determine which icon was selected. void menu_heading(void) ----------------------- This displays the menu heading which must have been previously defined with menu_bar_options. Example: -------- menu_heading(); The menu headings are displayed. void menu_display(int 1) ------------------------ Parameter 1 defines which menu to display.This call is only of real use on a menu driven application being first executed i.e. forcing the user straight into a menu selection. Example: -------- menu_display(3); Display menu 3 on screen. int long win_get_item(int 1,int 2) ---------------------------------- The window numbered parameter 1,item parameter 2 returns a value (possibly an address) as a long integer. Example: -------- value=win_get_item(5,3); Value would contain the value of item 3 in window 5. int menu_poll(void) ------------------- Begins polling of the menus.The returned value is a 'non window' key. Example: -------- key=menu_poll(); Polling of menus begins.Polling will be left when either a 'non window' key is pressed or a window gadgets type is such that it needs to return directly to the users program. void menu_kill(void) -------------------- This call must be issued once the application using the menus/windows ends,as any allocated memory during use is now released. Example: -------- menu_kill(); All menu/window workspace memory is released. Useful Global Variables ----------------------- int menu_position This always contains the currently selected menu int menu_option Contains the currently selected menu option int menu_fore_color The menu/window foreground color int menu_back_color The menu/window background color int menu_highlight_color The menu/window color for highlighted options/gadgets char *menu_bar_options The menu bar headings int menu_help_color Color for menu/window help text int win_accept Number of the currently active window char menu_buffer1[4096] Buffer to save screen behind menu int win_out User can set to 1,in order to leave menu poll loop Example skeleton code --------------------- To use the OBJ file include it in a project file along with your C source code plus of course any other object/source files.MCs Menu Maker uses far pointers therefore it will not work in tiny/small/medium memory models. The example below is very simple but illustrates how to use the various menu/window calls.The portion of code which displays the menu position and menu option may appear wrong after a selection is made and a different menu option highlighted,this is due to the way the screen updates and will not effect your own program. #include "mcs_menu.h" //Include MCs Menu header int menu_position=0; int menu_option=0; int menu_fore_color=15; //Foreground colour int menu_back_color=1; //Background colour int menu_highlight_color=4; //Highlight colour char menu_buffer1[4096]; char menu_buffer2[4096]; int menu_titles=0; char *menu_bar_options; int menu_menus=0; int window_windows=0; int window_x=0; int window_y=0; int win_attr=0; int win_out=0; char unsigned far *win_text_screen; int window_open=0; int window_item=0; int menu_help_color=14; int win_accept=0; int win_default=0; struct menu_help_def *startmh=NULL; struct menu_help_def *endmh=NULL; struct window_help_def *startwh=NULL; struct window_help_def *endwh=NULL; struct menu_def *start=NULL; struct menu_def *end=NULL; struct window_def *startw=NULL; struct window_def *endw=NULL; void main (void) { int key,quit=0; menu_clear(3); //Clear screen,get menu system ready //Declare menu menu_declare("{0}Menu option 0,{1}Menu option 1,Menu option 2 has no window"); menu_help_declare(0,0,"This is a menu option"); //Declare help for this menu_help_declare(0,1,""); //menus options menu_help_declare(0,2,"This option has no window"); // //Declare menu menu_declare("{0}Option 1,Option 2,Option 3,Option 4,EXIT"); menu_help_declare(1,0,""); // menu_help_declare(1,1,""); //Declare help for this menu_help_declare(1,2,""); //menus options menu_help_declare(1,3,""); // menu_help_declare(1,4,"Exit to DOS"); // //Declare windows window_declare(" A Sample Window ",74,12,0,0,"{1}{15}{2}{14}Some text,{2}{2}{1}{11}{4},{5}{8}{4}{6}{1},{0}"); window_declare(" Another Window ",40,15,5,5,"{6}{3}{4}{15}{0}A text string,{3}{3}{8}{1}{10}{5},{1}{2}{7}{7}Enter a value between 1 and 10,{0}"); //Menu heading titles menu_bar_options=" Menu-1 Menu-2 "; menu_heading(); //Display titles gettext(1,1,80,25,menu_buffer1); //Get background menu_display(0); //Display a starting menu do { key=menu_poll(); //Start polling the menus if (key==28) //BIOS code for 'Return' key { if (menu_position==1) // if (menu_option==4) //If this option,exit quit=1; // } gotoxy(10,20); // cprintf("menu selected: %d",menu_position); // gotoxy(10,21); //Display menu/option selected cprintf("menu option : %d",menu_option); // gotoxy(10,23); // } while (quit==0); //Do until this flag is 1 puttext(1,1,80,25,menu_buffer1); //Put background back } Example of managing a window work area -------------------------------------- Assuming a window (number 6) has been declared and contains a switch as item 4 and a char (input string) gadget as item 6,the following would set them, i.e. overriding any default. char *addr; char p; win_set_item(6,4,2); //Turn on switch 2 addr=(char *)win_get_item(6,6); //Get the address where the type //chars workspace is for(p=0;p!=3;p++) //Although a rough example,this *(addr+p)=p+65; //would fill the char workspace //with A,B,C,D in succession How to crash your PC! --------------------- Its assumed that C programmers are reasonably intelligent (!),therefore doing things such as trying to create a window larger than the screen,trying to place a gadget at x coordinate 1 million,declaring a char gadget of length 6 and attempting to store a 500K file in it and such things are virtually guranteed to crash your system.Also declaring a window without a {0} terminator and a window or menu with a gadget type (e.g. {1} for text) and then the wrong number of corrosponding parameters will send your PC into a mild epiletic fit!!!.Failure to allocate memory and "simple" errors should be trapped by the menu system and return a useful error message.Remember its not perfect but it does work!,have fun. END: - 26/08/92 - Mark Hula - Compuserve id: 100047,110